…ation guide (#254)

- README "Release status" now names v1.9.0 (codename "navigable") as Latest
  stable, and the "What's new" section covers in-document navigation, the
  native TOC / page references / bookmarks, multi-section documents, the
  per-page-margin / bleed / row-layout additions, inline chips / SVG / emoji,
  and render-to-images. Install snippets stay at 1.8.0 (the release tooling
  flips them at cut time).
- Add docs/roadmaps/migration-v1-8-to-v1-9.md — additive-only upgrade guide
  with a per-area TL;DR table, the one negative-margin behaviour note, the
  2.0-bound shim deprecations, and the upgrade snippet.
- Index the v1.8->v1.9 and the previously unlisted v1.7->v1.8 guides in
  docs/README.md.

…navigation (#256)

Four v1.9.0 features visible in a rendered document had no gallery presence.
Add a row + detailed showcase section + a committed preview render for each,
with the API names read off the runnable *Example classes:

- Inline highlight chips (RichText.code / chip / highlight) — Core DSL.
- Inline SVG icons (RichText.svgIcon) — Core DSL.
- Colour emoji by shortcode (RichText.emoji) — Core DSL.
- In-PDF navigation (anchor / linkTo / inlineLinkTo / shapeLinkTo) — Advanced SPI.

The emoji preview uses the 44 KB shortcode showcase; the full emoji-gallery
render is 3.9 MB, too large for a committed README asset.

…h 2 updates (#259)

Bumps the maven-minor-patch group with 2 updates in the / directory: [org.junit:junit-bom](https://github.com/junit-team/junit-framework) and [ch.qos.logback:logback-classic](https://github.com/qos-ch/logback).
Bumps the maven-minor-patch group with 2 updates in the /benchmarks directory: [org.junit:junit-bom](https://github.com/junit-team/junit-framework) and [ch.qos.logback:logback-classic](https://github.com/qos-ch/logback).
Bumps the maven-minor-patch group with 2 updates in the /examples directory: [org.junit:junit-bom](https://github.com/junit-team/junit-framework) and [ch.qos.logback:logback-classic](https://github.com/qos-ch/logback).


Updates `org.junit:junit-bom` from 6.1.0 to 6.1.1
- [Release notes](https://github.com/junit-team/junit-framework/releases)
- [Commits](junit-team/junit-framework@r6.1.0...r6.1.1)

Updates `ch.qos.logback:logback-classic` from 1.5.34 to 1.5.37
- [Release notes](https://github.com/qos-ch/logback/releases)
- [Commits](qos-ch/logback@v_1.5.34...v_1.5.37)

Updates `org.junit:junit-bom` from 6.1.0 to 6.1.1
- [Release notes](https://github.com/junit-team/junit-framework/releases)
- [Commits](junit-team/junit-framework@r6.1.0...r6.1.1)

Updates `ch.qos.logback:logback-classic` from 1.5.34 to 1.5.37
- [Release notes](https://github.com/qos-ch/logback/releases)
- [Commits](qos-ch/logback@v_1.5.34...v_1.5.37)

Updates `org.junit:junit-bom` from 6.1.0 to 6.1.1
- [Release notes](https://github.com/junit-team/junit-framework/releases)
- [Commits](junit-team/junit-framework@r6.1.0...r6.1.1)

Updates `ch.qos.logback:logback-classic` from 1.5.34 to 1.5.37
- [Release notes](https://github.com/qos-ch/logback/releases)
- [Commits](qos-ch/logback@v_1.5.34...v_1.5.37)

---
updated-dependencies:
- dependency-name: org.junit:junit-bom
  dependency-version: 6.1.1
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: maven-minor-patch
- dependency-name: ch.qos.logback:logback-classic
  dependency-version: 1.5.37
  dependency-type: direct:development
  update-type: version-update:semver-patch
  dependency-group: maven-minor-patch
- dependency-name: org.junit:junit-bom
  dependency-version: 6.1.1
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: maven-minor-patch
- dependency-name: ch.qos.logback:logback-classic
  dependency-version: 1.5.37
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: maven-minor-patch
- dependency-name: org.junit:junit-bom
  dependency-version: 6.1.1
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: maven-minor-patch
- dependency-name: ch.qos.logback:logback-classic
  dependency-version: 1.5.37
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: maven-minor-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

Bumps the github-actions group with 1 update: [actions/cache](https://github.com/actions/cache).


Updates `actions/cache` from 5 to 6
- [Release notes](https://github.com/actions/cache/releases)
- [Changelog](https://github.com/actions/cache/blob/main/RELEASES.md)
- [Commits](actions/cache@v5...v6)

---
updated-dependencies:
- dependency-name: actions/cache
  dependency-version: '6'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: github-actions
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Artem Demchyshyn <132658418+DemchaAV@users.noreply.github.com>

… release (#260)

The README hero (assets/readme/repository_showcase_render.png) carried a
hardcoded version constant and was rasterised by hand, so it drifted — it still
read v1.8.0 while the repo was on 1.9.0. Now it is single-sourced and rendered
straight from the engine:

- EngineDeckExample reads its version + codename from a Maven-filtered
  banner.properties (version=@project.version@, codename=navigable) instead of
  hardcoded constants, so the hero always carries the reactor version.
- The new ReadmeBannerRenderer writes the PNG straight from the engine via
  DocumentSession.toImage(0, dpi) — no render-to-PDF-then-PdfPageRasterizer
  round-trip. EngineDeckExample.renderBannerImage shares the banner composition
  with the (kept) PDF generateBanner via composeBannerInto.
- cut-release.ps1 re-renders the banner after the version bump and stages it in
  the release commit (gated under -not -SkipShowcase), so the committed hero
  ships in lockstep with every tag.
- VersionConsistencyGuardTest fails the build if banner.properties stops sourcing
  the version from @project.version@; ReadmeBannerRendererTest covers the render,
  the PNG write, and that filtering actually resolved.

The hero keeps its tight pageSize crop: the whole page is the banner via
pageBackground, which bleed() does not replace.

…9.0 emoji feature (#261)

The "What's new in v1.9" block names colour emoji via the independently-versioned
graph-compose-emoji module, but the install section gave no coordinate for it —
only the fonts companion artifact had a copy-paste dependency block. Add a
parallel graph-compose-emoji (1.0.0) snippet, noting emoji is opt-in (the bundle
stays fonts-only) and that an unknown shortcode falls back to literal text.

…o stamps the bumped version

Render-ReadmeBanner ran `exec:java ReadmeBannerRenderer` without compiling the
examples module. banner.properties is filtered to ${project.version} at
examples-compile time, and the cut never recompiles examples after the Step-1
version bump — so the re-rendered hero carried the PREVIOUS release version
(e.g. a v1.9.0 cut would have stamped "v1.8.0"). Add `compile` to the exec so
the module is rebuilt at the bumped version and banner.properties re-filters
before the render.

…tes guides (#263)

Add four developer-facing pages and wire them into the docs index.

- first-document.md — a five-minute path from an empty project to a
  rendered PDF: the smallest document, a multi-section custom flow, the
  built-in template shortcut, and server streaming.
- capabilities.md — a feature-to-API map giving the main call, the
  stability tier, and a guide link for each capability; the API stability
  policy stays authoritative for the contract.
- diagrams.md — Mermaid decision diagrams for the authoring path, content
  placement, output destination, and document lifecycle.
- templates/business-templates.md — the built-in InvoiceTemplateV2 and
  ProposalTemplateV2 compose-first contract, end to end, including the
  server-stream variant.

getting-started.md gains a one-line pointer to first-document.md, and the
docs README persona table and category index link the new pages.

The GitHub Pages deploy fired on both the main push and the v* release tag, but
the tag run failed every release: Pages refuses to deploy from a tag ref (the
github-pages environment only allows main), so it produced a red X without ever
deploying — and via cancel-in-progress could race-cancel the good main run. The
unconditional `push: branches: [main]` trigger (no paths filter) already covers
releases reliably, so the tag trigger is redundant. Remove it.

* test(docs): compile published Java snippets to catch API drift

DocumentationExamplesTest renders hand-kept Java copies of examples, but
nothing compiles the literal docs/*.md fences, so a published snippet can
drift from the API while the build stays green.

DocumentationSnippetCompileTest walks docs/**/*.md and, for each java fence
carrying an opt-in marker comment <!-- doc-example: id=... mode=... -->,
wraps it per mode (method / members / class) and compiles it in-memory via
ToolProvider.getSystemJavaCompiler() against the test classpath. Compiler
errors fail the test and name the snippet id + file; a second test guards
marker well-formedness, and the run asserts at least one snippet is found so
a moved docs folder cannot make the guard pass vacuously. Markers are HTML
comments, invisible on GitHub; teaching fragments stay unmarked.

Marks the five self-contained snippets in first-document.md (2) and
business-templates.md (3). Complements DocumentationExamplesTest, which
renders example copies; this guard pins the published markdown to the API.

* test(docs): self-test the snippet guard and tighten its parsing

Make DocumentationSnippetCompileTest verify its own failure path so a
regression in the parse/wrap/compile pipeline cannot pass vacuously:

- compilerReportsErrorForBrokenSnippet feeds a snippet that references a
  missing symbol and asserts the error is surfaced and attributed to its id.
- knownCanonicalTypeResolvesOnTestClasspath compiles a trivial canonical
  call, so a classpath failure is distinguishable from a documentation break.

Also harden the mechanics: attribute diagnostics to snippets by file-object
identity instead of a substring match; lift only the leading run of imports
(an import-shaped line inside a body stays put); match the java fence exactly
(no `javascript`); create the compiler output dir inside the try; guard
sanitized unit-name uniqueness. Drop the unused class mode.

#267)

The showcase site links to 85 example previews but only 53 are committed; the
other 32 — navigation, emoji, inline SVG/icons, layout, multi-section, charts,
debug overlay and the engine-deck / feature-catalog / financial-report
flagships — 404 on the live site.

Root cause: the blanket *.pdf ignore whitelists the old docs/showcase and
site/public/showcase locations but never web/showcase, where the live site now
lives, so every newly added preview was silently ignored and left out of the
release commit.

- .gitignore: whitelist web/showcase/**/*.pdf, matching the older site copies,
  so showcase previews are tracked and future examples ship automatically.
- Commit the 32 missing previews under web/showcase/pdf/** (regenerated with
  GenerateAllExamples).

Verified every pdf path in web/examples.json (85) resolves to a committed file;
the 53 already-tracked previews and examples.json are untouched.

#268)

30 showcase cards linked their "View Code" to a path that 404s. 26 examples
were never registered in ShowcaseMetadata, so the manifest fell back to the
examples-root URL with a filename-derived title and a generic description; 4
more (debug-overlay, block-align, svg-icon-gallery, vector-path) resolved
through the group→class switch to the wrong or a non-existent class. The
switch guessed the class from the group, which cannot work once a group holds
one class per id (layout, navigation, text, …).

- feature()/flagship() now take the example class explicitly, like cv() /
  letter(), dropping the brittle group→class switch.
- Register the 26 missing examples — in-document navigation, colour emoji,
  inline runs, per-page layout, charts, multi-section, the engine-deck /
  feature-catalog / financial-report flagships — each with a curated title, a
  one-line description naming the concrete DSL API, and tags.
- Point the 4 mis-resolved links at their real class (vector-path →
  VectorPathExample, etc.).
- groupLabel: add charts, navigation, structure, title, docx.
- Regenerate web/examples.json: exactly those 30 entries change, the other 55
  stay byte-identical, links kept at /blob/v1.9.0.

Verified the examples module compiles (ShowcaseSync BUILD SUCCESS) and every
code URL in web/examples.json (85/85) resolves to a committed .java file.

Bring the 15 commits on develop since the last integration into the 2.0
line: the v1.9.0 release, the showcase View-Code link + 404-PDF fixes, the
DocumentationSnippetCompileTest doc-snippet guard, the README hero banner
tooling, and dependency bumps.

Conflict resolutions:
- Versions stay 2.0.0-SNAPSHOT across every pom; develop's logback / junit
  bumps and the examples banner <resources> block are kept.
- CHANGELOG keeps the 2.0.0 Planned entry on top of the finalized v1.9.0
  section.
- The three cv/v2/components deprecated shims stay removed (develop only
  re-touched their @deprecated(since); the 2.0 line deletes them).
- PublicApiNoEngineLeakTest keeps the templates scan root and stays off the
  removed document.theme package.
- ShowcaseMetadata takes develop's richer feature gallery and explicit
  exampleClass wiring, minus the three entries whose examples the 2.0 line
  dropped (the canonical InvoiceFileExample / ProposalFileExample and
  CustomBusinessThemeExample); examples.json regenerates at release.
- The docs guides keep their 2.0-repointed bodies; the doc-example markers
  the new snippet-compile guard needs were re-added above the layered
  first-document and business-templates snippets so the guard compiles the
  current ModernInvoice / ModernProposal API.

Tests: ./mvnw verify javadoc:javadoc -pl . — 1382 tests, 0 failures, javadoc
clean; examples tests + perf-smoke + examples-generation smoke (85) green.